#!/usr/bin/env python3
'''ultrasonic ranging using I2C'''  # 使用I2C通信协议进行超声波测距
'''software tools : smbus'''        # 使用smbus库操作I2C总线
'''hardware       : KS103    '''    # 硬件使用KS103超声波传感器

import smbus   # 加载smbus通信库
import time

# 初始化I2C总线设备文件 (1表示使用/dev/i2c-1设备)
bus = smbus.SMBus(1) # open /dev/i2c-1 (对应GPIO2/3物理引脚)

# I2C设备参数配置
address = 0x74                      # i2c device address (7位地址，对应十六进制0x74)
wr_cmd = 0xb0                       # range 0-5m, return distance(mm) (写入寄存器的值为0xb0时，为测量距离模式，获得以mm为单位的距离)

# # 写入寄存器的值为0xb2时，范围0-5m，为测量距离模式，以时间计算，单位us可以获得超声波返回的时间，计算时间可以获得距离 (距离=时间x声速(340m/s)/2)
# rd_cmd = 0xb2                       # range 0-5m, return flight time(us), remember divided by 2

# 便于捕获Ctrl+C中断，从而清理资源并退出
try:
    # 主循环持续获取距离数据
    while True:
        # 发送测量指令（向地址0x74的寄存器0x2写入0xb0，以单位mm来计算）
        bus.write_byte_data(address, 0x2, wr_cmd)
        
        # 等待传感器测量完成 (根据设备要求至少33ms后读数据)
        time.sleep(1) # MIN ~ 0.033 (延时等待1s，确保数据稳定)
        
        # 读取两个数据寄存器 (高字节存储在0x02，低字节存储在0x03)
        HighByte = bus.read_byte_data(address, 0x2) # 获取距离值的高8位
        LowByte = bus.read_byte_data(address, 0x3)  # 获取距离值的低8位
        
        # 数据合成处理（将两个字节组合为16位整数）
        Dist = (HighByte << 8) + LowByte            # 位运算合并高低字节获得距离值
        
        # 输出转换后的距离值 (毫米转厘米，Python隐含精度控制，自动打印1位小数)
        print('Distance:', Dist/10.0, 'cm')

        #time.sleep(2)
        
except KeyboardInterrupt: # 处理Ctrl+C键盘中断信号
    pass

bus.close()             # 清理I2C资源
print('Range over!')    # 程序终止提示信息
